Summary

Adds optional local quota notifications to the macOS menubar app. The scope stays narrow: connected live-quota providers only, currently Claude and Codex, with alerts at the two thresholds people actually need to act on.

Behavior

• Adds a General Settings toggle for Quota alerts.
• Requests macOS notification permission only when the user enables the toggle.
• Evaluates connected Claude/Codex quota summaries when live quota state changes.
• Sends local notifications when an individual quota window crosses:
  • 80%: early warning
  • 100%: limit reached / over limit
• Evaluates each quota window independently so an already-notified 5-hour window cannot suppress a newly-crossed weekly window.
• If usage jumps straight from below 80% to 100%+, sends only the 100% notification and marks the lower threshold too.
• Presents banner/sound notifications even when the menubar popover or Settings window is foregrounded.

Example notification:

Claude quota at 86%
Weekly usage has crossed 80%.

Dedupe / Spam Control

Alerts are deduplicated in UserDefaults by:

• provider (claude, codex)
• quota window label (5-hour, Weekly, etc.)
• threshold (80, 100)
• reset token

Reset tokens use the exact reset timestamp when a provider supplies one, so multiple same-day rolling windows can alert independently. Windows without a reset timestamp fall back to the local calendar day. The coordinator also keeps an in-memory pending-key set so rapid observation refreshes cannot schedule the same notification twice before UserDefaults is written.

Old dedupe keys are pruned after 45 days, with pruning rate-limited to at most once per day.

Permission Handling

The app does not prompt from the background refresh path. Permission is requested only from Settings when the toggle is turned on. If notifications are later denied in System Settings, the toggle is disabled on the next settings sync and no hidden dedupe mark is written for undelivered alerts.

Validation

• npm run build - passed.
• swift build from mac/ - passed.
• npx vitest run tests/menubar-json.test.ts tests/day-aggregator.test.ts - 25/25 tests passed.
• git diff --check - passed.
• GitHub checks: assess, check, semgrep - passed.
• Argus-style review - PASS.
• Claude Opus 4.7 effort max review - PASS.
• Gemini 3.1 Pro Preview review - PASS.

Notes

• swift test --filter QuotaNotificationDeciderTests is still blocked before running the filtered tests by the existing Swift test-target/toolchain issue: no such module 'Testing' from unrelated existing test files.
• I did not validate live quota threshold delivery against a real over-limit provider state. Screenshot/manual validation will be posted separately after contributor review.